Signed CLA, awaiting update

Thanks for opening the PR @gkinsman!

Documentation is generated from tests to ensure that it stays in line with changes in the client.

I think this would be a good candidate for a "Search as you type" section under Search as opposed to extending the Usage test. It would follow a narrative, much like the "writing queries" section. Would you like to contribute such a section? This Stack Overflow answer could be used as a starting basis for it and such a section would include

1. What is required in the mapping to make completion suggester work i.e. CompletionField
2. How one queries using the Completion Suggester, showing both NEST API code and the JSON request
3. How to handle the response within NEST
4. Adding context with the Context Suggester

Ah! I totally missed the note at the top of the file :). I like that strategy a lot - I can certainly give it a red hot go. It looks like the tests should all be runnable locally using the in memory client - is that correct?

I'll give it a go tonight and see what I can turn out :)

Awesome 😄 It's been on the list of TODOs for some time so any PRs for documentation are hugely welcomed!

We have integration tests already for the completion suggester so for the documentation, using the InMemoryConnection would be a good approach. When running

.\build.bat

in the root, the unit tests will run, so will ensure all is as intended. Some pointers that I hope will help:

1. Probably want to derive from SerializationTestBase and implement IClusterFixture<ReadOnlyCluster> similar to the writing queries section.
2. [U] attribute for unit tests
3. Code that is needed for the tests but should not appear in documentation can be "attributed" with a //hide code comment. private members don't need this as the doc generation process only looks at public members.
4. Anonymous types can be serialized and shown as JSON in documentation by "attributing" the anonymous type with //json
5. Code annotations can be applied with // <1> comment here where the number should increment across a source block for each subsequent annotation.
6. AsciiDoc is strict about heading level ordering. Take a look at the Elastic docs README and ping me if you get stuck.

As a heads up, the DocGeneration project does not currently run and emit the asciidoc files (you'll see an error when running build.bat); MsBuildWorkspace does not properly support the newer csproj format, meaning that all of the source file documents under the project directory do not get automatically picked up and added to the Project type. We're working on fixing this, likely moving back to AdHocWorkspace for the moment.

Thanks again!

DocGeneration is now fixed, so you can see what the output asciidoc will look like when building the solution.

Heya @gkinsman, just a ping to see if you were still interested in looking at this?

Ah hey, yes! Great to hear the doc gen is now fixed, I struggled a bit last time without it :). Will take a look this weekend I think - still using and loving elastic :).

@gkinsman I'm going to close this PR in favour of adding an item to #2248 to cover off documentation for Suggesters. Keen to do another round on the docs when a good chance arises!

Thanks for bringing to attention 👍